.TH E1432_SET_ENABLE 3 E1432
.SH NAME
.nf
e1432_set_enable \- Enable or disable data for an input channel or group
e1432_get_enable \- Get group or channel enable value
.fi
.IX e1432_set_enable(3) 3
.IX e1432_get_enable(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_set_enable(E1432ID hw, SHORTSIZ16 ID,
                            SHORTSIZ16 data_type, SHORTSIZ16 setting)
SHORTSIZ16 e1432_get_enable(E1432ID hw, SHORTSIZ16 ID,
                            SHORTSIZ16 data_type, SHORTSIZ16 *setting)
.cE
.SH DESCRIPTION
This function enables or disables data from an input channel.  If data
is enabled, then \fIe1432_block_available\fR specifies when data is
available and the data transfer functions (\fIe1432_read_xxx_data\fR)
are used to read the data.  If data is disabled, data from the
specified channel is not made available to the host computer.

This parameter can be changed while a measurement is running, to allow
the host computer to look at only some of the data being collected by
the E1432 module.  Compare this with \fIe1432_set_active\fR, which
completely enables or disables a channel and which can't be changed
while a measurement is running.

\fIe1432_get_enable\fR returns the current enable value for a channel
or group.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

If the \fIID\fR is a channel ID, that one channel is set to
\fIsetting\fR.

\fIdata_type\fR specifies what type of data is being enabled or
disabled.  The valid values are \fBE1432_ENABLE_TYPE_TIME\fR, 
\fBE1432_ENABLE_TYPE_FREQ\fR, \fBE1432_ENABLE_TYPE_RESAMPLE\fR and
\fBE1432_ENABLE_TYPE_ORDER\fR.  The type of data that is available for
transfer to the host is determined by the \fIe1432_set_calc_data\fR
function, which must be called before the start of a measurement.  
If the data type has not been made available with this
function, then enabling its transmission to the host will be ignored.  
For instance, if resampling calculations are not being done for an input 
channel, then the enable value for \fRE1432_ENABLE_TYPE_RESAMPLE\fR for that
channel will be ignored.  


The \fIsetting\fR can be either \fBE1432_ENABLE_ON\fR or
\fBE1432_ENABLE_OFF\fR.  The default value is \fBE1432_ENABLE_ON\fR.

This parameter is used only by input channels.  Attempting to set or
change it for tach or source channels will result in an error.

If a particular \fBE1432_ENABLE_TYPE_xxx\fR is set to
\fBE1432_ENABLE_ON\fR, then the user wants to receive data of that
type for the channels referred to by the \fIID\fR.  If the
\fBE1432_ENABLE_TYPE_xxx\fR is set to \fBE1432_ENABLE_OFF\fR, then the
user does not want to receive data of that type for the channels
referred to by the \fIID\fR.

This enable setting for a particular channel is used only if the
channel is active, as set by \fIe1432_set_active\fR.  (Inactive input
channels never produce data, are not sent to local bus, and can't
trigger.)  Changing active/inactive on a channels stops a measurement.
In contrast, the enable setting can be changed while a measurement is
running without stopping the measurement.

The "enable" setting for a particular channel is used only for VME
data transfers.  The enable setting is completely ignored for local
bus transfers, so all active channels are always transferred to the
local bus.

The "enable" setting has no effect on input triggering - an input can
trigger whether data is enabled or not.

If a measurement is running, any changes to the "enable" setting take
place immediately.  (If the E1432 is in the MIDDLE of transferring a
scan of data to the host, then an error is generated and the changes
to the "enable" settings are not made.)  If the E1432 has already
asserted block available but has not started transferring data to the
host, then the change \fIdoes\fR take place immediately.

If \fIe1432_set_enable\fR is used to disable all data from all
channels in a group, then block available will no longer get asserted
in \fBE1432_IRQ_STATUS2_REG\fR, and \fIe1432_block_available\fR will
return 0 for any channel that is disabled.

If interrupts are being used for data transfer, then interrupts should
probably be blocked around the call to \fIe1432_set_enable\fR, so that
the interrupt handler can know if the new enable settings are in
effect.

The E1432 module ignores the "enable" settings when deciding whether
to assert an interrupt.  This means that a BLOCK READY interrupt will
happen even when all data from all channels is disabled.  This may
seem undesirable at first, but it is actually quite useful when doing
interrupt-driven multi-module measurements.  Because the interrupt will
happen even if all channels in a module are disabled, a single module
can be used to generate the BLOCK READY interrupts, even when all of
the channels in that module are disabled.  It is the responsibility of
the application to \fBnot\fR call \fIe1432_read_xxx_data\fR when there
is not actually any data available.  Note that
\fIe1432_block_available\fR will correctly return 0 for the disabled
channels, and 0 for the group ID, so this function can be used inside
an interrupt handler to determine if data is really available.

.SH "CORNER CASES"

Unfortunately, there are a couple corner cases where the data enable
functions don't work as cleanly as they should, and unfortunately it
is difficult to explain these corner cases in a simple way.
Fortunately, these really are corner cases which typical applications
will probably never see or care about.

These corner cases are an issue only if the application tries to
disable \fIall\fR data from \fIall\fR channels in one of the modules
of a multi-module measurement.  \fBSingle-module measurements are not
affected\fR.

.B "Corner Case 1"

If an application disables all data from all channels of a module in a
multi-module measurement, then there is no data for the host
application to read out of that module.  But the module must still
remain synchronized with other modules in the multi-module measurement
that do have enabled data.  To ensure synchronization, the
\fIe1432_block_available\fR function does some behind-the-scenes
communication with the modules.  When a scan of data is ready, the
\fIe1432_block_available\fR function tells the completely disabled
module to pretend that data was just read from it.  Then, when the
application reads data from the other modules in the measurement, all
the modules will stay synchronized.

This is all fine, but it means that \fBif there are any completely
disabled modules, once\fR \fIe1432_block_available\fR \fBhas returned
true (and has therefore told completely disabled modules to act like
data was already read), then it is too late to change the enabled
channels\fR.  If an application tries to enable data from the
completely disabled module at this time, the modules may not stay
synchronized, and possibly the measurement may hang waiting for the
next block available.

One reason this is not typically a problem is that applications
typically read data immediately after calling
\fIe1432_block_available\fR, if the function tells them that data is
ready.

.B "Corner Case 2"

If an application disables all data from all channels of all modules
in multi-module measurement, then there is no data for the host to
read at all.  In this case, \fIe1432_block_available\fR will always
return zero, because no data is ever ready for the host.

However, the modules still need to stay synchronized, so that when
data is eventually enabled by the application, that data is
synchronized properly.

For a multi-module measurement, this synchronization is performed by
\fIe1432_block_available\fR.  \fBSo it is necessary for the
application to regularly call\fR \fIe1432_block_available\fR \fBeven
though no data is enabled\fR.

One reason this is not typically a problem is that few applications
actually try to disable all data from all channels.  Another reason
this is not typically a problem is that many application already call
\fIe1432_block_available\fR frequently.  Even an interrupt-driven
application will not generally have problems with this, because the
modules will continue to generate data available interrupts even
though no data is enabled, so the interrupt handler will typically end
up calling \fIe1432_block_available\fR.

.SH "RESET VALUE"
See above.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.ne 3
.SH "SEE ALSO"
.na
e1432_block_available, e1432_create_channel_group, e1432_set_enable,
e1432_e1431_diff, e1432_set_calc_data
.ad
